home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / gemfut15.lzh / GEMXTEND.DOC < prev   
Text File  |  1990-08-06  |  23KB  |  484 lines
  1.  
  2. **************************************************************************
  3. *
  4. * GEMXTEND.DOC - Descriptions of extensions made to GEM bindings since
  5. *                the original TOS 1.0 release.
  6. *
  7. *  06/29/90    - v1.5
  8. *                Added function v_gchar() to output a single text char.
  9. *
  10. *  05/26/90    - v1.4
  11. *                Included documentation on the new calling standard,
  12. *                and the bindings that currently support it:
  13. *                   evnx_multi()
  14. *                   frmx_center()
  15. *                   winx_get()
  16. *                   winx_calc()
  17. *
  18. *  09/06/89    - v1.3
  19. *                This document is new with this release, and contains
  20. *                revisions through TOS 1.4.
  21. **************************************************************************
  22.  
  23. This document is divided into two sections.  Section 1 documents the 
  24. changes and additions Atari has made to the GEM routines in TOS.  Section 2 
  25. documents alternate calling standards to the existing functions.  These
  26. alternate bindings provide more efficient ways to call AES functions.
  27.  
  28.  
  29. **************************************************************************
  30. *
  31. * Section 1 - Changes Atari has made to GEM/TOS.
  32. *
  33. **************************************************************************
  34.  
  35. This section describes extensions Atari has made to TOS/GEM since the
  36. original TOS 1.0 operating system.  When Atari adds new VDI/AES functions,
  37. appropriate bindings will be created and documented here.  Note that some
  38. of the functions listed here have been available since TOS 1.0, but Atari
  39. neglected to document them.  The title bar for each function lists the
  40. first TOS version that supported the function.  Other functions have 
  41. backwards compatibility built into the GEMFAST binding so that they will 
  42. work correctly on all TOS versions (these are noted in the title bars too).
  43.  
  44. *--------------------------------------------------------------------------
  45. * About TOS 1.4...
  46. *--------------------------------------------------------------------------
  47.  
  48.  The TOS 1.4 pre-release notes contain documentation for the following:
  49.  
  50.    form_error    form_alert    shel_write    shel_get    shel_put  
  51.    fsel_exinput  wind_new
  52.  
  53.  Of these, the form_error/alert and shel_???? docs seem to be just a 
  54.  clarification of the docs without any functional changes.
  55.  
  56.  The wind_new and fsel_exinput functions are new with TOS 1.4.
  57.  
  58. ;-------------------------------------------------------------------------
  59. ; wind_new                    TOS 1.4
  60. ;-------------------------------------------------------------------------
  61.  
  62.   void wind_new();
  63.  
  64.   The 'wind_new' function is for doing a major cleanup after a GEM 
  65.   application.  It closes & deletes all windows, flushes all the windows'
  66.   buffers (of redraw msgs, I presume), clears the wind_update flag, and
  67.   restores ownership of the mouse to the system (END_MCTRL I presume). The
  68.   documentation is not clear on whether this function should be used by
  69.   an application that wants to shut down everything quickly, or whether it
  70.   is intended for a shell's use in cleaning up after an application exits.
  71.   I tend to suspect the latter, and I think this function was developed 
  72.   because shell writers all begged Atari to provide something that could
  73.   clean up after an application the way the desktop does.
  74.  
  75. ;-------------------------------------------------------------------------
  76. ; fsel_exinput                TOS 1.4 (binding compatible with 1.0 and up)
  77. ;-------------------------------------------------------------------------
  78.  
  79.   Full 1.4 emulation...
  80.  
  81.   status = fsel_exinput(in_path, in_sel, &exitbtn, prompt_text);
  82.   
  83.    (status and exitbtn are 16-bit ints, others are char *).
  84.    
  85.  This routine is functionally equivelent to fsel_input, except that it
  86.  also allows you to specify a prompt string of up to 30 characters to be
  87.  displayed along with the file selector.  While the function is new with
  88.  TOS 1.4, the AESFAST bindings support it in all versions via a routine
  89.  which checks the AES version number and simulates the actions of
  90.  fsel_exinput by using fsel_input and objc_draw.  If running under
  91.  TOS 1.4, the system will display your prompt text in place of the words
  92.  'FILE SELECTOR' inside the fsel box.  If running under pre-TOS 1.4, the
  93.  simulation routines place the prompt text in a box which appears 
  94.  between the menu bar and the fsel box.
  95.  
  96.  Other TOS 1.4 changes to the fsel routines that this routine supports 
  97.  via simulation when running on pre-TOS 1.4 systems...
  98.  
  99.   - The file selector now allows you to edit the pathname and hit RETURN
  100.     without exiting the dialog.  If you edit the filename and hit <CR>,
  101.     you will exit as if you clicked on OK.
  102.   - If the initial pathname has a leading '\', it will be appended to the
  103.     end of the current default drive and path, and the entire resulting
  104.     string will be returned if the user exits via OK or <CR>.
  105.   - The current default drive and path are preserved, and the contents
  106.     of the current DTA are preserved.  Only the default path on the 
  107.     default drive is saved with the simulation software. If the user
  108.     changes devices during file selection, the default path on all devices
  109.     may  be changed except for the device that was the default when 
  110.     fsel_exinput was called.
  111.  
  112.   The executable code for the fsel_exinput binding is big -- about 800
  113.   bytes.  Also, it uses about 350 bytes of stack space during the call.
  114.   Still, having a prompted file selector that works correctly on all
  115.   machines will lend a touch of class to your application (IMHO).
  116.  
  117.   Note that all of the above fsel ehancements which are supported by the
  118.   simulation on pre-TOS 1.4 systems are supported ONLY if you call
  119.   fsel_exinput; if you call fsel_input on a pre-1.4 system the default
  120.   path et. al. will behave as they always have. (Hint: USE exinput).
  121.  
  122. ;-------------------------------------------------------------------------
  123. ; fsel_smallexinput           TOS 1.4 (binding compatible with 1.0 and up)
  124. ;-------------------------------------------------------------------------
  125.  
  126.   Prompting emulation only...
  127.  
  128.   This function has calling parameters identical to fsel_exinput() (see
  129.   above), but it's behavior (return values, etc) is identical to that of
  130.   fsel_input() (the original).  This function will call the real 'exinput'
  131.   routine if on TOS 1.4, but if on an earlier version it emulates only the
  132.   prompting of 'exinput', it does not save the path or DTA, or handle <CR>
  133.   correctly, or any of the other nice TOS 1.4 features.  On the other hand,
  134.   it's only half as big as the full emulator for fsel_exinput(), so it's
  135.   handy for accessories and other small-memory applications.  (It will add
  136.   about 450 bytes to your program, as opposed to 800).        
  137.   
  138.   I'd like to recommend that you do not code calls to fsel_smallexinput()
  139.   directly in your program.  Instead, just code fsel_exinput(), and at the
  140.   top of your C source, code:
  141.   
  142.     #define fsel_exinput fsel_smallexinput
  143.  
  144.   and let the C compiler handle the rest for you.  This ought to keep your
  145.   code compatible many years into the future...
  146.  
  147. ;-------------------------------------------------------------------------
  148. ; fsel_14input              TOS 1.4 (binding compatible with 1.0 and up)
  149. ;-------------------------------------------------------------------------
  150.  
  151.   No emulation.
  152.  
  153.   This function has calling parameters identical to fsel_exinput() (see
  154.   above).  However, it makes no attempt to emulate any of the 1.4 exinput
  155.   features.  Basically, if running on TOS 1.4, fsel_exinput is called.  If
  156.   running on a pre-1.4 system, the prompt string is thrown away, and the
  157.   normal file selector is called.  This binding is very small compared to
  158.   other (emulation mode) exinput bindings.
  159.   
  160.   Again, it is best to access this function through a #define statement:
  161.   
  162.     #define fsel_exinput fsel_14input
  163.  
  164. | This function was added with v1.4.
  165.  
  166. ;-------------------------------------------------------------------------
  167. ; shel_get / shel